/*!
 * \file IParserApi.h
 * \project	WonderTrader
 *
 * \author Wesley
 * \date 2020/03/30
 * 
 * \brief 行情解析模块接口定义文件
 * 
 * \details 该文件定义了WonderTrader系统中行情解析相关的接口，包括：
 *          - 行情解析器接口（IParserApi）：统一的行情数据解析接口
 *          - 行情解析回调接口（IParserSpi）：处理解析后的行情数据
 *          
 *          这些接口为量化交易系统提供了统一的行情数据获取能力，支持：
 *          - 多种行情数据源（CTP、XTP、YD、UDP等）
 *          - 实时行情数据推送（Tick、Level2数据等）
 *          - 合约信息管理和订阅机制
 *          - 统一的连接管理和错误处理
 *          - 灵活的行情适配器架构
 */
#pragma once
#include <string>
#include <stdint.h>
#include "WTSTypes.h"
#include "FasterDefs.h"

NS_WTP_BEGIN
class WTSTickData;
class WTSOrdDtlData;
class WTSOrdQueData;
class WTSTransData;
class WTSVariant;
class WTSArray;
class IBaseDataMgr;

/*!
 * \class IParserSpi
 * \brief 行情解析模块回调接口
 * 
 * \details 行情解析器的回调接口，用于处理各种行情数据和事件：
 * 
 * **主要功能：**
 * - **连接管理**: 处理连接建立、断开等状态变化
 * - **合约管理**: 处理合约列表的获取和更新
 * - **行情推送**: 处理实时行情数据的接收和分发
 * - **Level2数据**: 处理深度行情数据（委托队列、成交明细等）
 * - **日志处理**: 统一的日志信息处理机制
 * 
 * **支持的数据类型：**
 * - **Tick数据**: 最新价、买卖盘、成交量等基础行情
 * - **委托队列**: Level2委托排队数据
 * - **委托明细**: Level2逐笔委托数据
 * - **成交明细**: Level2逐笔成交数据
 * 
 * \note 该接口是行情系统的核心回调接口，所有行情适配器都需要实现
 * \see IParserApi
 */
class IParserSpi
{
public:
	/*!
	 * \brief 处理行情解析器事件
	 * \param[in] e 事件类型，包括连接、断开、错误等事件
	 * \param[in] ec 错误代码，0为没有错误
	 * 
	 * \details 处理行情解析器的各种状态变化事件：
	 *          - 连接建立成功/失败
	 *          - 连接断开
	 *          - 登录成功/失败
	 *          - 订阅成功/失败
	 *          - 系统错误等
	 * 
	 * \note 默认为空实现，子类可根据需要重写
	 */
	virtual void handleEvent(WTSParserEvent e, int32_t ec){}

	/*!
	 * \brief 处理合约列表
	 * \param[in] aySymbols 合约列表，数组元素为WTSContractInfo
	 * 
	 * \details 当行情解析器获取到合约列表时被调用：
	 *          - 合约基本信息（代码、名称、乘数等）
	 *          - 交易规则（最小变动价位、涨跌停等）
	 *          - 交易时段信息
	 *          - 保证金比率等
	 * 
	 * \note 该方法必须被实现，用于接收和处理合约信息
	 * \see WTSArray, WTSContractInfo
	 */
	virtual void handleSymbolList(const WTSArray* aySymbols)		= 0;

	/*!
	 * \brief 处理实时行情数据
	 * \param[in] quote 实时行情数据
	 * \param[in] procFlag 处理标记：
	 *                     - 0: 纯数据推送，不需要额外处理（如ParserUDP）
	 *                     - 1: 需要缓存，需要去重（用于多路径场景）
	 *                     - 2: 需要缓存，需要价格聚合，需要形成其他时间周期数据（tick、m1、m5等自动聚合的，如果不需要则不聚合）
	 * 
	 * \details 处理从行情源接收到的实时Tick数据：
	 *          - 最新价、买卖价、买卖量
	 *          - 成交量、成交额
	 *          - 涨跌幅、开高低收
	 *          - 持仓量（期货）等
	 * 
	 * \note 该方法必须被实现，是行情数据的主要入口
	 * \see WTSTickData
	 */
	virtual void handleQuote(WTSTickData *quote, uint32_t procFlag)	= 0;

	/*!
	 * \brief 处理委托队列数据（股票Level2）
	 * \param[in] ordQueData 委托队列数据
	 * 
	 * \details 处理Level2深度行情中的委托队列数据：
	 *          - 十档买卖盘委托数量分布
	 *          - 每个价位的委托订单数量
	 *          - 委托队列的实时变化
	 * 
	 * \note 默认为空实现，仅在需要Level2数据时重写
	 * \see WTSOrdQueData
	 */
	virtual void handleOrderQueue(WTSOrdQueData* ordQueData){}

	/*!
	 * \brief 处理逐笔委托数据（股票Level2）
	 * \param[in] ordDetailData 逐笔委托数据
	 * 
	 * \details 处理Level2深度行情中的逐笔委托数据：
	 *          - 每笔委托的详细信息
	 *          - 委托类型（买入/卖出/撤单等）
	 *          - 委托价格和数量
	 *          - 委托时间戳
	 * 
	 * \note 默认为空实现，仅在需要Level2数据时重写
	 * \see WTSOrdDtlData
	 */
	virtual void handleOrderDetail(WTSOrdDtlData* ordDetailData){}

	/*!
	 * \brief 处理逐笔成交数据
	 * \param[in] transData 逐笔成交数据
	 * 
	 * \details 处理逐笔成交明细数据：
	 *          - 每笔成交的价格和数量
	 *          - 成交时间
	 *          - 买卖方向
	 *          - 成交性质（主动买入/主动卖出等）
	 * 
	 * \note 默认为空实现，仅在需要成交明细时重写
	 * \see WTSTransData
	 */
	virtual void handleTransaction(WTSTransData* transData){}

	/*!
	 * \brief 处理行情解析器日志
	 * \param[in] ll 日志级别
	 * \param[in] message 日志消息
	 * 
	 * \details 处理来自行情解析器的日志信息：
	 *          - 调试信息
	 *          - 警告信息
	 *          - 错误信息
	 *          - 系统状态信息
	 * 
	 * \note 该方法必须被实现，用于统一的日志处理
	 */
	virtual void handleParserLog(WTSLogLevel ll, const char* message)	= 0;

public:
	/*!
	 * \brief 获取基础数据管理器
	 * \return 基础数据管理器指针
	 * 
	 * \details 返回基础数据管理器实例，用于获取合约信息、交易日历等基础数据
	 * 
	 * \note 该方法必须被实现
	 */
	virtual IBaseDataMgr*	getBaseDataMgr()	= 0;
};

/*!
 * \class IParserApi
 * \brief 行情解析模块接口
 * 
 * \details 统一的行情解析API接口，提供完整的行情数据获取功能：
 * 
 * **核心功能：**
 * - **连接管理**: 建立和维护与行情服务器的连接
 * - **数据订阅**: 灵活的合约订阅和退订机制
 * - **实时推送**: 高效的行情数据实时推送
 * - **状态监控**: 连接状态和数据质量监控
 * 
 * **支持的行情源：**
 * - CTP行情（期货、期权）
 * - XTP行情（股票、基金、债券）
 * - YD行情（期货）
 * - UDP广播行情
 * - 其他第三方行情源
 * 
 * **技术特性：**
 * - 统一的接口设计，支持多种行情系统
 * - 异步处理机制，保证高性能
 * - 完善的重连机制和错误处理
 * - 灵活的适配器架构，便于扩展
 * 
 * \note 该接口为纯虚接口，具体实现由各行情适配器提供
 * \see IParserSpi
 */
class IParserApi
{
public:
	/*!
	 * \brief 虚析构函数
	 * 
	 * \details 确保派生类能够正确析构，释放相关资源
	 */
	virtual ~IParserApi(){}

public:
	/*!
	 * \brief 初始化行情解析器
	 * \param[in] config 模块配置参数
	 * \return 是否初始化成功
	 * 
	 * \details 使用指定参数初始化行情解析器：
	 *          - 解析配置参数
	 *          - 初始化网络连接
	 *          - 设置行情环境
	 *          - 准备认证信息等
	 * 
	 * \note 默认返回false，子类必须重写实现具体的初始化逻辑
	 */
	virtual bool init(WTSVariant* config) { return false; }

	/*!
	 * \brief 释放行情解析器
	 * 
	 * \details 释放行情解析器相关资源：
	 *          - 断开网络连接
	 *          - 清理内存资源
	 *          - 保存必要的状态信息
	 * 
	 * \note 默认为空实现，子类应重写实现具体的资源清理逻辑
	 */
	virtual void release(){}

	/*!
	 * \brief 开始连接服务器
	 * \return 连接请求是否发送成功
	 * 
	 * \details 建立与行情服务器的网络连接：
	 *          - TCP连接建立
	 *          - 心跳机制启动
	 *          - 登录认证处理
	 *          - 连接状态监控
	 * 
	 * \note 默认返回false，子类应重写实现具体的连接逻辑
	 */
	virtual bool connect() { return false; }

	/*!
	 * \brief 断开连接
	 * \return 断开请求是否发送成功
	 * 
	 * \details 主动断开与行情服务器的连接：
	 *          - 停止心跳机制
	 *          - 关闭网络连接
	 *          - 清理连接状态
	 * 
	 * \note 默认返回false，子类应重写实现具体的断开逻辑
	 */
	virtual bool disconnect() { return false; }

	/*!
	 * \brief 检查连接状态
	 * \return 是否已连接
	 * 
	 * \details 检查当前与行情服务器的连接状态
	 * 
	 * \note 默认返回false，子类应重写实现状态检查逻辑
	 */
	virtual bool isConnected() { return false; }

	/*!
	 * \brief 订阅合约列表
	 * \param[in] setCodes 合约代码集合
	 * 
	 * \details 订阅指定合约的行情数据：
	 *          - 支持批量订阅
	 *          - 支持通配符订阅
	 *          - 自动去重处理
	 *          - 订阅状态跟踪
	 * 
	 * \note 默认为空实现，子类应重写实现具体的订阅逻辑
	 * \see CodeSet
	 */
	virtual void subscribe(const CodeSet& setCodes){}

	/*!
	 * \brief 退订合约列表
	 * \param[in] setCodes 合约代码集合
	 * 
	 * \details 退订指定合约的行情数据：
	 *          - 支持批量退订
	 *          - 支持部分退订
	 *          - 自动状态更新
	 * 
	 * \note 默认为空实现，子类应重写实现具体的退订逻辑
	 * \see CodeSet
	 */
	virtual void unsubscribe(const CodeSet& setCodes){}

	/*!
	 * \brief 注册回调接口
	 * \param[in] spi 回调接口实现
	 * 
	 * \details 注册行情事件回调接口，用于接收各种行情数据和事件
	 * 
	 * \note 默认为空实现，子类应重写实现回调注册逻辑
	 */
	virtual void registerSpi(IParserSpi* spi) {}
};

NS_WTP_END

/*!
 * \typedef FuncCreateParser
 * \brief 创建行情解析器的函数指针类型
 * 
 * \details 用于动态加载行情适配器时创建行情解析器实例的函数指针类型
 */
typedef wtp::IParserApi* (*FuncCreateParser)();

/*!
 * \typedef FuncDeleteParser
 * \brief 删除行情解析器的函数指针类型
 * 
 * \details 用于动态加载行情适配器时销毁行情解析器实例的函数指针类型
 */
typedef void(*FuncDeleteParser)(wtp::IParserApi* &parser);